home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / CW GUSI 1.6.4 / doc / pod / GUSI_Install.pod < prev    next >
Encoding:
Text File  |  1995-04-20  |  5.8 KB  |  181 lines  |  [TEXT/CWIE]
  1. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  2. %  Project  :  GUSI        -  Grand Unified Socket Interface
  3. %  File     :  GUSI.web    -  Documentation
  4. %  Author   :  Matthias Neeracher
  5. %  Language :  C SpiderWeb
  6. %  
  7. %  $Log: GUSI.web,v $
  8. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  9.  
  10. =head1 Installing and using GUSI
  11.  
  12. This section discusses how you can install
  13. C<GUSI> on your disk and use it for your programs.
  14.  
  15. To install C<GUSI>, change in the MPW Shell to its directory and type:
  16.  
  17.    BuildProgram Install <Enter>
  18.  
  19. This will install all necessary files in C<{CIncludes}>, C<{CLibraries}>, and
  20. C<{RIncludes}>, respectively. It will also install C</etc/services> in your preferences
  21. folder, prompting you if you have an older version there.
  22.  
  23. This requires that you have MPW Perl installed, which is available in the same ftp 
  24. directory as C<GUSI>.
  25.  
  26. To use C<GUSI>, include one or more of the following header files in your
  27. program:
  28.  
  29. =over 4
  30.  
  31. =item C<GUSI.h>
  32. The main file. This includes almost everything else.
  33.  
  34. =item C<TFileSpec.h>
  35. C<FSSpec> manipulation routines.
  36.  
  37. =item C<dirent.h>
  38. Routines to access all entries in a directory.
  39.  
  40. =item C<netdb.h>
  41. Looking up TCP/IP host names.
  42.  
  43. =item C<netinet/in.h>
  44. The address format for TCP/IP sockets.
  45.  
  46. =item C<sys/errno.h>
  47. The errors codes returned by GUSI routines.
  48.  
  49. =item C<sys/ioctl.h>
  50. Codes to pass to C<ioctl()>.
  51.  
  52. =item C<sys/socket.h>
  53. Data types for socket calls.
  54.  
  55. =item C<sys/stat.h>
  56. Getting information about files.
  57.  
  58. =item C<sys/types.h>
  59. More data types.
  60.  
  61. =item C<sys/uio.h>
  62. Data types for scatter/gather calls.
  63.  
  64. =item C<sys/un.h>
  65. The address format for Unix domain sockets.
  66.  
  67. =item C<unistd.h>
  68. Prototypes for most routines defined in GUSI.
  69.  
  70. =back
  71.  
  72. GUSI expects the Macintosh Toolbox to be initialized. This will happen automatically
  73. under some circumstances (if you're writing an C<MPW> tool with the non-CodeWarrior
  74. compilers or if you are linking with C<SIOW> and are forcing a write to standard 
  75. output or standard error before you are using any non-file C<GUSI> routines, but
  76. it's often wiser to do an explicit initialization anyway.
  77.  
  78. You should init the Toolbox in the following way:
  79.  
  80.       InitGraf((Ptr) &qd.thePort);
  81.       InitFonts();
  82.       InitWindows();
  83.       InitMenus();
  84.       TEInit();
  85.       InitDialogs(nil);
  86.       InitCursor();
  87.  
  88. You have to link your program with the C<GUSI> library. The exact procedure differs
  89. slightly between the C<MPW C> version, the C<PPCC> version, and the C<CodeWarrior>
  90. version. 
  91.  
  92. =head2 Linking with MPW C GUSI
  93.  
  94. For the  C<MPW C> version, you should link with C<{CLibraries}GUSI.o>, 
  95. and optionally one or several I<configuration files>. Currently, the following
  96. configuration files exist:
  97.  
  98. =over 4
  99. =item C<GUSI_Everything.cfg>
  100. Include code for everything defined in C<GUSI>.
  101. =item C<GUSI_Appletalk.cfg>
  102. Include code for AppleTalk sockets.
  103. =item C<GUSI_Internet.cfg>
  104. Include code for MacTCP sockets.
  105. =item C<GUSI_PAP.cfg>
  106. Include code for PAP sockets.
  107. =item C<GUSI_PPC.cfg>
  108. Include code for PPC sockets.
  109. =item C<GUSI_Unix.cfg>
  110. Include code for Unix domain sockets.
  111. =back
  112.  
  113. If you don't specify any configuration files, only the file related routines will be
  114. included. It's important that these files appear I<before> all other libraries.
  115.  
  116. Linking with C<GUSI> doesn't free you from linking in the standard libraries,
  117. typically:
  118.  
  119.     {Libraries}Runtime.o
  120.     {Libraries}Interface.o
  121.     {CLibraries}StdCLib.o
  122.     {Libraries}ToolLibs.o
  123.  
  124. =head2 Linking with PPCC GUSI
  125.  
  126. For the C<PPCC> version, you should link with C<{PPCLibraries}GUSI.xcoff> and 
  127. if you are linking with SIOW, also with C<{PPCLibraries}GUSI.xcoff>. The C<PPCC>
  128. version currently doesn't support flexible configuration. Like with the C<MPW C> 
  129. version, C<GUSI> should be first in your link, and you have to link with the 
  130. standard libraries.
  131.  
  132. C<GUSI> for C<PPCC> makes use of Code Fragment Manager version numbers,
  133. therefore you have to specify the correct version number for C<MakePEF> with the C<-l>
  134. option.
  135.  
  136.    -l "GUSI.xcoff=GUSI#0x01508000-0x01508000"
  137.  
  138. In case you were wondering, this encodes the version number (1.5.0) the same way as the 
  139. header of a C<'vers'> resource.
  140.  
  141. =head2 Linking with CodeWarrior GUSI
  142.  
  143. The easiest way to get started with a C<CodeWarrior> C<GUSI> application is by
  144. cloning from the appropriate project stationery in the Lib directory. The principle
  145. of operation is the same as with the other versions: First C<GUSI.Lib>, and then
  146. the standard libraries have to be specified. To create an MPW tool with the
  147. CodeWarrior compilers, you additionally have to link with C<GUSIMPW.Lib> before
  148. C<GUSI.Lib>
  149.  
  150. The C<CodeWarrior> version uses a new configuration mechanism that will eventually be 
  151. adapted in the other versions as well: At the beginning of your application,
  152. call C<GUSISetup> for the components you need. Currently, the following 
  153. components are defined:
  154.  
  155. =over 4
  156. =item C<GUSISetup(GUSIwithSIOUXSockets)>
  157. Allows use of the C<SIOUX> library for standard I/O.
  158. =item C<GUSISetup(GUSIwithAppleTalkSockets)>
  159. Includes ADSP sockets.
  160. =item C<GUSISetup(GUSIwithInternetSockets)>
  161. Includes TCP and UDP sockets.
  162. =item C<GUSISetup(GUSIwithPAPSockets)>
  163. Includes PAP sockets.
  164. =item C<GUSISetup(GUSIwithPPCSockets)>
  165. Includes PPC sockets.
  166. =item C<GUSISetup(GUSIwithUnixSockets)>
  167. Includes Unix domain sockets.
  168. =back
  169.  
  170. If you call C<GUSIDefaultSetup()> instead, all of the above will be included.
  171. These calls should be included right at the beginning of your C<main()> procedure.
  172.  
  173. =head2 Warning messages, Rezzing
  174.  
  175. You will get lots of warning messages about duplicate definitions, but that's ok 
  176. (Which means I can't do anything about it).
  177.  
  178. You should also rez your program with C<GUSI.r>. The section L<GUSI_Advanced/Resources>
  179. discusses when and how to add your own configuration resource to customize C<GUSI>
  180. defaults. Don't forget that your C<PowerPC> programs also need a C<cfrg> resource.
  181.